Cloudinaryの画像変換パラメータまとめ〜オーバーレイ・アンダーレイ

画像や動画を最適化できるSaaS・Cloudinaryでは様々な画像変換パラメータが提供されています。今回はそのうち、画像や文字によるオーバーレイとアンダーレイについてまとめていきます。

#デザイン

#Cloudinary

Ito ma

2020.05.09

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

Guten Abend、ベルリンから伊藤です。

画像や動画の最適化SaaSのCloudinaryで使用する画像変換パラメータについてまとめています。前回は形や回転・透過などのスタイルに関するものを説明しました。今回はオーバーレイとアンダーレイについて、Cloudinaryのドキュメントに沿ってまとめていきます。

画像変換パラメータのまとめ記事の一覧はこちら：

Cloudinaryの配信URL（おさらい）

詳しくは以前のブログにありますが、Cloudinaryを使った画像や動画の最適化・変換は、そのURL内のパラメータによって、動的に行うことができます。

https://res.cloudinary.com/[クラウド名]/[リソースタイプ]/[タイプ]/[変換パラメータ]/[バージョン]/[パブリックID].[フォーマット]

この [変換パラメータ] の中で、カンマ区切りで順不同でパラメータを指定でき、スラッシュ区切りで連続の変換を行うことができます。（※ただし、同じパラメータの組み合わせでも順序を変更して異なるパスとなると、異なるリクエストとしてCDNキャッシュからの配信がされません。）

画像の変換パラメータ

今回は画像におけるオーバーレイ・アンダーレイの変換オプションについて説明します。

オーバーレイ・アンダーレイの基本構造
画像のオーバーレイ・アンダーレイ
- 重ねた画像の変換: サイズ
- 重ねた画像の変換: 配置
テキストのオーバーレイ・アンダーレイ
ウォーターマークの除去防止

オーバーレイ・アンダーレイの基本構造

オーバーレイ・アンダーレイでは、画像や文字を指定した位置へ重ね、さらに変換を組み合わせることができます。パラメータは、オーバーレイが l_ 、アンダーレイが u_ から始まり、重ねる画像またはテキストを続けて指定します。

Image with watermark

この例では元の画像（ito-test/Reichstag）を変換して、その右下にロゴ（logo）を半透明で重ねています。変換パラメータ部分の大まかな構成は、次のようになります。

[元の画像の変換]/[重ねる画像],[重ねる画像の変換]
- [元の画像の変換]: c_scale,w_300
- [重ねる画像]: l_logo
- [重ねる画像の変換]: c_scale,g_south_east,w_100,x_10,y_10,o_70

https://res.cloudinary.com/CLOUD-NAME/image/upload/c_scale,w_300/l_logo,c_scale,g_south_east,w_100,x_10,y_10,o_70/v1/ito-test/Reichstag.jpg

では具体的な指定の方法について見ていきましょう。

画像のオーバーレイ・アンダーレイ

重ねる画像の指定には2つの方法があり、オーバー(l_)/アンダーレイ(u_)に続けて、以下の通り指定します。

Cloudinaryストレージ上の画像の場合： [パブリックID] （フォルダ配下のパスは folder/image→folder:image のようにスラッシュをコロン区切りに置き換える）
外部パブリックURLからフェッチする場合： fetch:[base64エンコードされたURL]

画像オーバーレイの例で見てみましょう。

# Cloudinary上の画像
https://res.cloudinary.com/CLOUD-NAME/image/upload/c_scale,w_300/l_ito-test:old_logo/v1/ito-test/Reichstag.jpg
# 外部URLからフェッチ
https://res.cloudinary.com/CLOUD-NAME/image/upload/c_scale,w_300/l_fetch:aHR0cDovL2Nsb3VkaW5hcnkuY29tL2ltYWdlcy9vbGRfbG9nby5wbmc=/v1/ito-test/Reichstag.jpg

1つ目はCloudinaryストレージ上の ito-test/old_logo.png を使用し、2つ目は外部URL http://cloudinary.com/images/old_logo.png から取り込んでいます。指定方法は異なりますが、今回は同じ画像を使っているためいずれも下記の変換結果となります。

なお、フェッチはこのように手動でURL作成する場合は手動でbase64への変換が必要ですが、Cloudinary SDK を使用すれば自動でエンコーディングされます。以下はNode.jsで実行して変換URLを取得する例です。

cloudinary.image("ito-test/Reichstag",
 { secure: true, transformation: [
 	{ width: 300, crop: "scale" },
 	{ overlay: {url: "http://cloudinary.com/images/old_logo.png" }}
 ]})

こちらは画像アンダーレイに変換を加えた例です。

ベース画像は幅 300px の楕円形（c_scale,w_300,r_max）とし、その背面にアンダーレイとして先ほどのロゴを挿入しています。アンダーレイの画像の変換としてサイズ・配置・グレースケール（w_300,g_south,e_grayscale）を指定しています。

https://res.cloudinary.com/CLOUD-NAME/image/upload/c_scale,w_300,r_max/u_ito-test:old_logo,w_300,g_south,e_grayscale/v1/ito-test/Reichstag.jpg

このように、重ねた画像もリサイズやスタイル、エフェクトなど変換パラメータを適用させることができます。

重ねた画像の変換: サイズ

重ねた画像の幅・高さのサイズ調整は、以前のブログでも解説されているのと同様に、ピクセル（w_100=幅 100px）やオリジナルからの割合（h_0.5=高さ 50%）で指定できます。

さらにオーバーレイ・アンダーレイの場合、ベースとなる本体の画像から相対的にサイズや配置を指定することも可能です。

割合指定に relative フラグを加えることで、ベースとなる画像サイズに対する割合でサイズを指定します。次の例で、w_0.5 のみでオリジナルの50%である幅 150px を指定した場合と w_0.5,fl_relative でベース画像の50%である 100px を指定した場合の違いが分かります。（bo_1px_solid_gray は枠線のパラメータでオーバーレイ画像に灰色の枠線を付与しています。）

fl_relative example

重ねた画像の変換: 配置

デフォルトは中心（g_center）のため、gravityオプションの方角による指定（g_north、g_south_westなど）やXY座標オプションで配置を定めます。両方組み合わせることもでき、次の例ではいずれも x_50,y_20 を適用していますが、左は何も指定しない(またはg_centerと指定した）場合、右はg_south_westと組み合わせた場合です。

placing absolute example

XYオプションは割合指定も可能で、ベースとなる画像サイズに対する割合で配置されます。以下の例ではベース画像が幅200x高さ150で、x_0.1,y_0.1 と指定するとそれぞれ20pxと15pxとなります。この際、XYの割合指定を行うとサイズも割合指定でなければならないことに注意してください。例のようにサイズについては前述の通り relative フラグの有無で違いがあります。

placing relative example

■ g_faces オプション

gravityオプションの方角による指定以外にも、 g_face、g_faces オプションを使用して、 ベースとなる画像で検知された顔に配置することもできます。

これは顔をマスクしたい時に便利で、合わせてオーバーレイのサイズを割合指定として region_relative フラグを加えることで、検知された顔サイズに対する割合でサイズを指定することもできます。例えば、l_mask,g_faces,w_1.5,fl_region_relative ではベースとなる画像で検知されたすべての顔の上に、顔の幅の150%のサイズで画像 mask が配置されます。

さらに応用して、次の例では変換した画像を顔の上に配置しています。

Overlay on Faces

めそ子（全身）の画像 ito-test/mesoko.png
顔部分だけ繰り抜くよう正方形に変換 w_500,c_fill,g_north,ar_1:1
円形・白背景・顔の110%のサイズ w_1.1,r_max,c_lpad,b_white,fl_region_relative
ベース画像の顔に配置 g_faces

https://res.cloudinary.com/CLOUD-NAME/image/upload/l_ito-test:mesoko,w_500,c_fill,g_north,ar_1:1/w_1.1,r_max,c_lpad,b_white,fl_region_relative/g_faces,fl_layer_apply/w_500/v1/lv.jpg

最後に含まれる layer_apply フラグは、このように多重変換を行う場合に区切りの最後として含めます。オーバーレイ画像に対してスラッシュ区切りで連続して変換を行なったり、複数の画像をオーバーレイで重ねるような場合に、括弧を閉じるようにスラッシュ区切りの連続した変換をそこまででまとめてくれます。詳細はドキュメントをご確認ください。

もし顔が検知されなければ、オーバーレイは含まれません。

■オーバーレイのタイル配置

tiled フラグを使用することで、オーバーレイをベース画像の全体に繰り返し配置することができます。

次の例では、ベースの画像を幅 200px（c_scale,w_200）とし、上段では50pxのオーバーレイをタイル配置（l_logo,w_50,fl_tiled）しています。左下は前述の relative フラグを使ってベース画像の30%にオーバーレイのサイズを調整しています。右下はタイル間の空間を広げるために150%の余白（c_lpad,w_1.5）としてから幅50pxに調整（w_50）しており、layer_apply フラグを使ってこの変換の結合を行なっています。

fl_tiled example

このように、複数のフラグを組み合わせる場合は、fl_[フラグ1].[フラグ2].[フラグ3] とピリオド区切りで指定可能です。Cloudinaryのこちらの記事でより詳細に例が紹介されています。

なお、このタイル配置はアンダーレイに使うことはできません。背景に画像をタイル配置させたい場合には、次のように 1) ベース画像のサイズ調整、2) タイル配置させる背景をオーバーレイ、3) ベース画像をオーバーレイとしてさらに重ねる、という一工夫が必要です。

Image with tiled background

https://res.cloudinary.com/CLOUD-NAME/image/upload/w_300,r_max/l_logo,w_100,fl_tiled/l_ito-test:Reichstag,w_300,r_max/v1/ito-test/Reichstag.jpg

テキストのオーバーレイ・アンダーレイ

文字を重ねる場合には、オーバー(l_)/アンダーレイ(u_)に続けて、text:[文字スタイル]:[文字列]のように指定します。

文字スタイルは下記のようなパラメータが指定でき、アンダースコア区切りで繋げます。（*は必須パラメータ）

パラメータ	説明	例
フォント*	世界的に利用できるフォント（Googleのフォント）（※）	Arial, Times, Courier, Impact
文字サイズ*	pxサイズ（数字）	50
スタイル	太字、斜体、下線、打ち消し線など	bold、italic、underline、strikethrough
配置位置	左寄り（デフォルト）、中央、など	left、center、right

SDKでの指定等の詳細、すべての一覧はドキュメントをご確認ください。

※Cloudinaryにフォントをアップロードすることでカスタムフォントを使うことも可能です。

次の例で、テキストオーバーレイとその変換を見てみましょう。

Image with text overlay

オーバーレイ: l_text:montserrat_25_style_light_align_center:This%20is%20Reichstag!
- フォント Montserrat
- サイズ 25px
- 細字（light）
- 中央配置（align_center）
- エンコーディングされた「This is Reichstag!」
文字色: co_rgb:ffffff
文字のサイズと配置（ベース画像の50%サイズ、中央から20%下に配置）: c_scale,fl_relative,w_0.5,y_0.2

https://res.cloudinary.com/CLOUD-NAME/image/upload/c_fill,g_auto,h_250,w_970/c_scale,co_rgb:ffffff,fl_relative,l_text:montserrat_25_style_light_align_center:This%20is%20Reichstag!,w_0.5,y_0.2/v1/ito-test/Reichstag.jpg

■特殊文字

特殊文字は、%を用いたUTF8エンコーディングでエスケープする必要があり、さらにカンマ（,）やパーセント（%）、スラッシュ（/）等はダブルエスケープが必要になります。以下、いくつか例を挙げます。

? = %3F
(スペース) = %20
改行 = %0A
% = %25
, = %252C
/ = %252F
☺ (スマイル絵文字) = %25E2%2598%25BA
♡ (ハート) = %25E2%2599%25A1
? (サングラス絵文字) = %25F0%259F%2598%258E

ただし、こちらも Cloudinary SDK を使用すれば自動でエンコーディングが行われるので考慮は不要です。

■改行・長文の処理

文字列を改行させるには、上記の特殊文字で改行を手動で加えることができます。

長文を指定する場合に、自動改行させることもできます。テキストオーバーレイの変換に幅サイズ指定（w_）と c_fit の切り抜きオプションを追加することで自動で改行させることができ、さらに高さサイズ指定（h_）をすると、そのサイズを超える範囲は文字が切られ「...」が加えられます。詳細、具体的な例はドキュメントをご参考ください。

■定義済みテキストのオーバーレイ

Cloudinary API の text メソッドを使って、テキストオーバーレイの文字スタイルを事前定義することも可能です。複数のアセットに対して統一したスタイルを簡単に適用させたり、より簡潔なURLでテキストオーバーレイを実現したりする場合に便利です。こちらも詳細はドキュメントをご参考ください。

ウォーターマークの除去防止

Cloudinary はデフォルトでは即座の変換が可能で、URLパラメータを修正することで誰でも簡単に新しい変換画像を作成することができます。しかし、特にウォーターマークが除去されないよう、URLパラメータの操作だけで画像変換されないようにしたい場合、Cloudinaryには以下の設定があります。

Strict 変換

アカウントでこのオプションを有効にすると、URLパラメータ操作による動的な変換は無効となり、事前に生成・許可した変換のみが利用できるようになります。これはアカウント単位の設定で有効にするとすべてのアセットに適用されます。ただし、有効化する以前に生成された変換は残り続けるので、作成してしばらく経っているアカウントで有効にする場合は注意が必要です。詳細はドキュメントをご確認ください。